package de.servicezombie.tcmdb.rest.service;

import java.io.InputStream;

import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;

import de.servicezombie.pub.r1.CommonRestResponse;
import de.servicezombie.tcmdb.TcmdbRecordNotFoundException;
import de.servicezombie.tcmdb.rest.vo.WsListResult;
import de.servicezombie.tcmdb.rest.vo.WsTestcaseDefinition;

/**
 * <b>Examples</b>
 * 
 * <pre>
 *  GET /testcase-definitions/active/by-application/webshop.xml
 *  GET /testcase-definitions/archived/by-application/webshop.xml
 *  
 *  // update or create a new testcase. if does not exist, TCD-0815 is ignored
 *  POST /testcase-definitions/active/save/Webshop/Search%20Features/TCD-0815.xml
 *  
 *  // create a new testcase
 *  POST /testcase-definitions/all/save/new.xml
 *  
 *  // add an existing testcase to archive mode
 *  PUT /testcase-definitions/active/by-id/TCD-0815/archive.xml
 * </pre>
 * 
 * @author ChKa
 * @see WsTestcaseDefinition
 */
@Path("/testcase-definitions")
@Consumes({ "test/json", "application/json", "test/xml", "application/xml" })
@Produces({ "test/json", "application/json", "test/xml", "application/xml" })
public interface TestcaseDefinitionService {

	/**
	 * @param applicationName
	 *            name of application, whoose testcases should be returned
	 * @response {@link WsListResult} of {@link WsTestcaseDefinition} in {@link CommonRestResponse}
	 */
	@GET
	@Path("/{type}/by-application/{application}")
	void getDefinitionsByApplication(
			@PathParam("type") String type, 
			@PathParam("application") String applicationName);

	/**
	 * Save a new testcase definition or overwrite an exising one.
	 * 
	 * @param definitionId id of testcase definition to overwrite or 'new' 
	 * for insert a new definition
	 * @param definitionStream xml structure to save
	 * @response {@link WsTestcaseDefinition} in {@link CommonRestResponse}. Contains id of new created record.
	 * @throws TcmdbRecordNotFoundException if record, which should be woverwritten does not exist
	 */
	@POST
	@Path("/all/save/{definitionId}")
	void save(
			@PathParam("definitionId") String definitionId,
			InputStream definitionStream) throws TcmdbRecordNotFoundException;

	/**
	 * archive an existing record. if record does not exist throws an exception
	 * @param definitionId id of an existing testcase
	 * @response void
	 */
	@PUT
	@Path("/active/by-id/{definitionId}/archive")
	void archive(@PathParam("definitionId") String definitionId);

	@GET
	@Path("/{type}/by-id/{definitionId}")
	void getDefinitionsById(
			@PathParam("type") String type, 
			@PathParam("definitionId") String definitionId) throws TcmdbRecordNotFoundException;

}
